# AutoHideCursor Plugin for VisualNEO Win

## Overview
The **AutoHideCursor** plugin automatically hides the mouse cursor after a period of inactivity and shows it again when the mouse moves. This is perfect for video playback, image viewing, presentations, and any application where you want the cursor to disappear during idle periods.

## Features
- ✅ Automatic cursor hiding after configurable timeout
- ✅ Instant cursor reappear on mouse movement
- ✅ Global mouse tracking (works anywhere on screen)
- ✅ Manual cursor control (hide/show on demand)
- ✅ Adjustable timeout without restarting
- ✅ Status variables for scripting logic
- ✅ Automatic cleanup on program exit

## Installation

### Method 1: Compile from Source
1. Open **AutoHideCursor.pb** in PureBasic
2. Set compiler options:
   - **Format**: Shared DLL
   - **Architecture**: x86 (32-bit)
   - **Character set**: ASCII
3. Compile the DLL
4. Rename **AutoHideCursor.dll** to **AutoHideCursor.nbp**
5. Copy to your VisualNEO Win **PlugIns** folder
   - Default: `C:\Program Files\VisualNEOWin\PlugIns\`

### Method 2: Install Pre-compiled
1. Copy **AutoHideCursor.nbp** to the VisualNEO Win **PlugIns** folder
2. Restart VisualNEO Win or use **Options → Install Plug-Ins**

## Commands

### 1. startAutoHideCursor
**Syntax**: `startAutoHideCursor "[timeout_ms]"`

Starts the auto-hide functionality with the specified timeout.

**Parameters**:
- `timeout_ms` - Time in milliseconds before cursor hides (e.g., 3000 = 3 seconds)

**Example**:
```
startAutoHideCursor "3000"    . Hide after 3 seconds
startAutoHideCursor "5000"    . Hide after 5 seconds
startAutoHideCursor "1500"    . Hide after 1.5 seconds
```

---

### 2. stopAutoHideCursor
**Syntax**: `stopAutoHideCursor`

Stops the auto-hide functionality and ensures the cursor is visible.

**Parameters**: None

**Example**:
```
stopAutoHideCursor
```

---

### 3. setAutoHideTimeout
**Syntax**: `setAutoHideTimeout "[timeout_ms]"`

Changes the timeout value without stopping and restarting the auto-hide feature.

**Parameters**:
- `timeout_ms` - New timeout in milliseconds

**Example**:
```
setAutoHideTimeout "2000"    . Change to 2 seconds
setAutoHideTimeout "10000"   . Change to 10 seconds
```

---

### 4. hideCursorNow
**Syntax**: `hideCursorNow`

Immediately hides the cursor without waiting for timeout. The cursor will reappear when the mouse moves if auto-hide is active.

**Parameters**: None

**Example**:
```
hideCursorNow
```

---

### 5. showCursorNow
**Syntax**: `showCursorNow`

Immediately shows the cursor.

**Parameters**: None

**Example**:
```
showCursorNow
```

## Status Variables

The plugin sets two VisualNEO Win variables that you can use in your scripts:

### [AutoHideCursorActive]
- **Values**: "True" or "False"
- **Description**: Indicates whether auto-hide monitoring is currently active

### [CursorVisible]
- **Values**: "True" or "False"
- **Description**: Indicates whether the cursor is currently visible

**Example Usage**:
```
. Check if auto-hide is running
If "[AutoHideCursorActive]" "=" "True"
    AlertBox "Info" "Auto-hide is currently active"
EndIf

. Check cursor visibility
If "[CursorVisible]" "=" "False"
    . Cursor is hidden - maybe show it for user interaction
    showCursorNow
EndIf
```

## Usage Examples

### Example 1: Video Player
```
. When video starts playing
startAutoHideCursor "3000"

. When video stops or pauses
stopAutoHideCursor
```

### Example 2: Image Slideshow
```
. Start slideshow with auto-hide
startAutoHideCursor "4000"

. Temporarily show cursor for user controls
showCursorNow

. Hide again immediately
hideCursorNow

. End slideshow
stopAutoHideCursor
```

### Example 3: Presentation Mode
```
. Enter presentation mode with 5-second delay
startAutoHideCursor "5000"

. During presentation, adjust timeout if needed
SetVar "[UserTimeout]" "7000"
setAutoHideTimeout "[UserTimeout]"

. Exit presentation mode
stopAutoHideCursor
```

### Example 4: Conditional Auto-Hide
```
. Only enable auto-hide if user preference is set
If "[UserPreferences.AutoHideCursor]" "=" "Yes"
    startAutoHideCursor "3000"
EndIf

. Later, check status
If "[AutoHideCursorActive]" "=" "True"
    . Auto-hide is running
    SetVar "[StatusMessage]" "Cursor will auto-hide"
Else
    SetVar "[StatusMessage]" "Auto-hide disabled"
EndIf
```

### Example 5: Full Screen Application
```
. On PageEnter for full-screen page
startAutoHideCursor "2000"

. On button click - temporarily show cursor
OnClick:
    showCursorNow
    . Do something...
    . Cursor will auto-hide again after 2 seconds of no movement

. On PageLeave
stopAutoHideCursor
```

## How It Works

### Technical Details
1. **Mouse Hook**: Uses Windows low-level mouse hook (`WH_MOUSE_LL`) to monitor all mouse movements globally
2. **Timer System**: Implements a precise timer to track inactivity periods
3. **Cursor API**: Uses Windows `ShowCursor()` API for hiding/showing
4. **Thread-Safe**: All operations are thread-safe and won't conflict with VisualNEO Win
5. **Auto-Cleanup**: Automatically releases all hooks and resources when VisualNEO Win exits

### Performance
- Minimal CPU usage - only processes mouse movement events
- No polling - event-driven architecture
- Automatic cleanup prevents memory leaks
- Works seamlessly with VisualNEO Win's event system

## Troubleshooting

### Cursor Won't Hide
- **Check timeout value**: Make sure you're using milliseconds (3000 = 3 seconds, not 3)
- **Verify auto-hide is started**: Use `[AutoHideCursorActive]` variable
- **Move mouse completely still**: Any tiny movement resets the timer

### Cursor Won't Show Back
- **Move the mouse**: Even a tiny movement will trigger cursor to show
- **Force show**: Use `showCursorNow` command
- **Stop and restart**: Try `stopAutoHideCursor` then `startAutoHideCursor "3000"`

### Plugin Not Appearing in VisualNEO Win
- **Check file extension**: Must be .nbp (not .dll)
- **Verify location**: Should be in VisualNEO Win's PlugIns folder
- **Reinstall**: Use Options → Install Plug-Ins menu
- **Restart**: Restart VisualNEO Win after installation

## Best Practices

### 1. Always Stop on Page Exit
```
. On PageLeave
stopAutoHideCursor
```
This ensures clean state transitions between pages.

### 2. Use Reasonable Timeouts
- **Too short** (<1000ms): Cursor will flicker, annoying to users
- **Too long** (>10000ms): Defeats the purpose
- **Recommended**: 2000-5000ms (2-5 seconds)

### 3. Provide User Control
Let users enable/disable or adjust timeout:
```
. Settings page
SetVar "[UserTimeout]" "3000"  . Default 3 seconds
. ... user adjusts with slider or input field ...

. Apply settings
startAutoHideCursor "[UserTimeout]"
```

### 4. Check Status Before Actions
```
. Before hiding cursor manually
If "[CursorVisible]" "=" "True"
    hideCursorNow
EndIf
```

### 5. Combine with Other Features
```
. When entering fullscreen video mode
SetVar "[PrevCursorState]" "[CursorVisible]"
startAutoHideCursor "3000"
. ... maximize window, hide controls, etc ...

. When exiting fullscreen
stopAutoHideCursor
If "[PrevCursorState]" "=" "False"
    hideCursorNow  . Restore previous state
EndIf
```

## Compatibility
- ✅ Windows XP and higher
- ✅ VisualNEO Win 4.0 and higher
- ✅ Works in both development and compiled publications
- ✅ Compatible with all VisualNEO Win objects and actions

## Version History

### Version 1.0 (2024)
- Initial release
- 5 commands: start, stop, setTimeout, hideNow, showNow
- 2 status variables
- Global mouse tracking
- Automatic cleanup

## Credits
**Author**: Anthony C  
**Language**: PureBasic 6.21  
**License**: Freeware  
**Support**: For questions or issues, contact through VisualNEO Win forums

## Notes
- The cursor hiding is system-wide when activated, not just within VisualNEO Win window
- Moving the mouse even 1 pixel will show the cursor again
- Multiple calls to `startAutoHideCursor` will restart the monitoring with new timeout
- The plugin automatically cleans up when VisualNEO Win exits or publication closes

---

**Enjoy using AutoHideCursor! Perfect for creating professional, distraction-free viewing experiences.**
